<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Advanced use" />
		<title>PDF Graphics .NET documentation - Advanced use</title>
		<link rel="stylesheet" href="style/Help.css" type="text/css" />
	
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="Index.html">Help</a> :: Advanced use
			</span>
		</div>
		
		<h1>Advanced use</h1>
		
		<p>
			This section covers the following topics:
			<ul>
				<li><a href="#Units">Page units</a></li>
				<li><a href="#Pages">Custom pages</a></li>
				<li><a href="#Orientation">Display orientation</a></li>
			</ul>
		</p>
			
		<h2><a name="Units"></a>Page units</h2>
		
		<p>
			All graphics operations are implicitly expressed in units, called 'page units'. By default, the unit used is
			the Point, or 1/72<sup>nd</sup> of an inch. You can change the unit used by graphics operation at any point by setting
			the <span class="code">PageUnit</span> property of a <span class="code">Graphics</span> instance to one of the following
			values:
		</p>
		
		<dl>
			<dt>Centimetres</dt>
			<dd>All operations will be expressed in centimetres. One inch is 2.54 centimetres.</dd>

			<dt>Inches</dt>
			<dd>All operations will be expressed in inches. There are 72 points in an inch.</dd>

			<dt>Millimetres</dt>
			<dd>All operations will be expressed in millimetres. There are 25.4 millimetres in an inch.</dd>

			<dt>Pixels</dt>
			<dd>
				All operations will be expressed in pixels. This is translated into points through the resolution
				of the <span class="code">Graphics</span> object. See below for more details.
			</dd>

			<dt>Points</dt>
			<dd>(default) All operations will be expressed in points.</dd>
		</dl>		
		
		<p>
			<strong>Note:</strong> Some values and operations are always expressed in points, regardless of the current
			page unit. Font size and spacing values used in rendering text are always expressed in points.
		</p>
		
		<h3>Resolution</h3>
		
		<p>
			Although PDF Graphics.NET deals with vector graphics (expect for images) and is therefore not dependent on
			device resolution, it does have an intrinsic resolution that is used to convert values in pixels to values
			in points. This resolution is only interesting while the <span class="code">PageUnit</span> property of the
			<span class="code">Graphics</span> object is set to <span class="code">Pixels</span>.
		</p>
		
		<p>
			By default, the resolution is set to 72 dpi in both X and Y direction. This means that a pixel corresponds
			to a point, since they are both 1/72<sup>nd</sup> of an inch. To change these values, use the
			<span class="code">DpiX</span> and <span class="code">DpiY</span> properties of the
			<span class="code">Graphics</span> class.
		</p>
		
		<h2><a name="Pages"></a>Custom pages</h2>
		
		<p>
			Graphics are always rendered on a page. If you don't explicitly create a page in your PDF document,
			PDF Graphics .NET will implicitly create a DIN A4 page. To create a new page, use the
			<span class="code">NewPage()</span> method. This method has three overloads:
		</p>
		
		<dl>
			<dt><span class="code">NewPage()</span></dt>
			<dd>
				Creates a new page with the same dimensions as the current page. For a
				<span class="code">Graphics</span> instance that was constructed without an explicit page size,
				this defaults to DIN A4.
			</dd>

			<dt><span class="code">NewPage(float width, float height)</span></dt>
			<dd>
				Creates a new page with the specified width and height. The width and height are expressed in
				points, regardless of the page unit of the <span class="code">Graphics</span> instance.
			</dd>

			<dt><span class="code">NewPage(Rectangle bounds)</span></dt>
			<dd>
				Creates a new page based on the specified rectangle. Only the width and height of the rectangle
				are considered; its position is not relevant. The width and height are expressed in points,
				regardless of the page unit of the <span class="code">Graphics</span> instance.
			</dd>
		</dl>		
		
		<p>
			You can also create a <span class="code">Graphics</span> instance with a preset size, using one of
			its constructor overloads. This is functionally equivalent to creating an instance and calling
			<span class="code">NewPage()</span> overload with a page size.
		</p>
		
		<h3>Standard pages</h3>
		
		<p>
			PDF Graphics .NET has a number of standard pages that can be used to create pages in popular formats.
			They standard pages are found in the <span class="code">StandardPages</span> static class, and can be
			used in overloads of <span class="code">NewPage()</span> as well as the
			<span class="code">Graphics</span> constructors. The full list of standard pages is as follows:
		</p>
		
		<dl>
			<dt>A0</dt>
			<dd>
				The DIN A0 paper format is the largest format in the list of DIN/ISO pages.
				It is approximately  33.1&quot; x 46.8&quot; in size.
			</dd>
			
			<dt>A1</dt>
			<dd>
				The DIN A1 paper format is a large paper format specified by DIN. It is approximately 
				23.4&quot; x 33.1&quot; in size.
			</dd>

			<dt>A2</dt>
			<dd>
				The DIN A2 paper format is a popular large paper format. It is approximately 
				16.5&quot; x 23.4&quot; in size.
			</dd>

			<dt>A3</dt>
			<dd>
				The DIN A3 paper format is a popular large paper format, twice the size of an A4 sheet.
				It is approximately  11.7&quot; x 16.5&quot; in size.
			</dd>

			<dt>A4</dt>
			<dd>
				DIN A4 is the most popular page size internationally. It is 8.26&quot; x 11.7&quot; in size.	
				Because of its popularity, it is the default page size in the PDF Graphics .NET library. 
			</dd>

			<dt>A5</dt>
			<dd>
				A DIN A5 page is half the size of an A4 page. It is 5.83&quot; x 8.26&quot;.
			</dd>

			<dt>A6</dt>
			<dd>
				DIN A6 is the smallest paper size in the DIN list. It is approximately
				4.14&quot; x 5.83&quot;.
			</dd>

			<dt>Legal</dt>
			<dd>
				The US legal format is a long and narrow page. It is approximately
				8.5&quot; x 14&quot;.
			</dd>

			<dt>Letter</dt>
			<dd>
				The US Letter format is a popular page format that is approximately
				8.5&quot; x 11&quot; in size.
			</dd>

			<dt>Tabloid</dt>
			<dd>	
				The US tabloid page is a large sheet format of approximately
				11&quot; x 17&quot;.
			</dd>
		</dl>
				
		<h2><a name="Orientation"></a>Display orientation</h2>
				
		<p>
			The standard set of page sizes included in the PDF Graphics.NET library is mostly based on portrait-oriented
			sheets. To create a landscape-oriented page you can do either of the following:
		</p>
		
		<ul>
			<li>
				Use <span class="code">NewPage()</span> and specify a <span class="code">Rectangle</span> instance with
				the appropriate dimensions; the width being the long side.
			</li>
			
			<li>
				Create a regular page and rotate the coordinate space using <span class="code">TransformTranslate()</span>
				and <span class="code">TransformRotate()</span>, or <span class="code">Reorient()</span>;
			</li>
		</ul>
		
		<p>
			When viewing the PDF document, any landscape-oriented pages will appear as landscape-oriented pages; with their
			long sides across. This is convenient for viewing the document on-screen but may cause issues when printing.
		</p>
		
		<p>
			The PDF standard allows a document to specify the display direction of a page. In PDF Graphics .NET, this is
			controlled through an overload of <span class="code">NewPage()</span> that accepts an
			<span class="code">Orientation</span> argument.
		</p>
		
		<p>
			Using the <span class="code">Orientation</span> argument, you can pass a landscape page size to
			<span class="code">NewPage()</span> and still display it with the short side across, like portrait pages.
		</p>
		
		<p>
			It can also be used to orient pages upside-down, which may be a requirement for some printers.
		</p>
		
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="graphics/Colour_schemes.html">&lt; Colour schemes</a> | <a href="Reference.html">Library reference&gt;</a>
		
	</body>
	
</html>